home *** CD-ROM | disk | FTP | other *** search
/ DOpus Plus / DOpus Plus.iso / SDK / docs / dos.doc < prev    next >
Encoding:
Text File  |  1998-10-26  |  19.9 KB  |  552 lines
  1. dopus5.library/DateFromStrings                 dopus5.library/DateFromStrings
  2.  
  3.     NAME
  4.         DateFromStrings - convert date and time strings to a datestamp
  5.  
  6.     SYNOPSIS
  7.         DateFromStrings(date, time, ds)
  8.                          A0    A1   A2
  9.  
  10.         BOOL DateFromStrings(char *, char *, struct DateStamp *);
  11.  
  12.     FUNCTION
  13.         This routine takes a date string and a time string and converts them
  14.         to a DOS DateStamp. The DOS StrToDate() routine is used to perform
  15.         this conversion, so it is sensitive to the current locale. If the
  16.         time string contains an 'a' or a 'p' to signify am or pm, it
  17.         is automatically converted to 24 hour time for the DOS call.
  18.  
  19.     INPUTS
  20.         date - date string to convert
  21.         time - time string to convert
  22.         ds - DateStamp to store result
  23.  
  24.     RESULT
  25.         Returns TRUE if successful.
  26.  
  27.     NOTES
  28.         This routine expects the date string in the FORMAT_DOS format
  29.         (dd-mmm-yy). DateFromStringsNew() offers more control.
  30.  
  31.     SEE ALSO
  32.         ParseDateStrings(), DateFromStringsNew(), dos.library/StrToDate()
  33.  
  34. dopus5.library/DateFromStringsNew           dopus5.library/DateFromStringsNew
  35.  
  36.     NAME
  37.         DateFromStringsNew - convert date and time strings to a datestamp
  38.  
  39.     SYNOPSIS
  40.         DateFromStringsNew(date, time, ds, method)
  41.                             A0    A1   A2    D0
  42.  
  43.         BOOL DateFromStrings(char *, char *, struct DateStamp *, ULONG);
  44.  
  45.     FUNCTION
  46.         This routine takes a date string and a time string and converts them
  47.         to a DOS DateStamp. The DOS StrToDate() routine is used to perform
  48.         this conversion, so it is sensitive to the current locale. If the
  49.         time string contains an 'a' or a 'p' to signify am or pm, it
  50.         is automatically converted to 24 hour time for the DOS call.
  51.  
  52.     INPUTS
  53.         date - date string to convert
  54.         time - time string to convert
  55.         ds - DateStamp to store result
  56.         method - date string format (eg FORMAT_DOS, FORMAT_CDN, etc)
  57.  
  58.     RESULT
  59.         Returns TRUE if successful.
  60.  
  61.     SEE ALSO
  62.         ParseDateStrings(), dos.library/StrToDate()
  63.  
  64. dopus5.library/DeviceFromHandler             dopus5.library/DeviceFromHandler
  65.  
  66.     NAME
  67.         DeviceFromHandler - returns device name from handler
  68.  
  69.     SYNOPSIS
  70.         DeviceFromHandler(handler, buffer)
  71.                             A0       A1
  72.  
  73.         struct DosList *DeviceFromHandler(struct MsgPort *, char *);
  74.  
  75.     FUNCTION
  76.         This function takes a pointer to a filesystem's handler
  77.         (message port) and returns the associated device name.
  78.  
  79.     INPUTS
  80.         handler - pointer to handler message port
  81.         buffer - buffer to store device name (must be >=34 bytes)
  82.  
  83.     RESULT
  84.         If the port supplied is a valid filesystem handler, the
  85.         name of the device is stored in the supplied buffer, and
  86.         a pointer to the DosList entry for that device is returned.
  87.  
  88.     SEE ALSO
  89.         DeviceFromLock(), DevNameFromLock()
  90.  
  91. dopus5.library/DeviceFromLock                   dopus5.library/DeviceFromLock
  92.     NAME
  93.         DeviceFromLock - returns device name from a filelock
  94.  
  95.     SYNOPSIS
  96.         DeviceFromLock(lock, buffer)
  97.                         A0     A1
  98.  
  99.         struct DosList *DeviceFromLock(BPTR, char *);
  100.  
  101.     FUNCTION
  102.         This function takes a filelock and returns the name of the
  103.         device that lock resides on.
  104.  
  105.     INPUTS
  106.         lock - pointer to lock
  107.         buffer - buffer to store device name (must be >=34 bytes)
  108.  
  109.     RESULT
  110.         The name of the device is stored in the supplied buffer, and
  111.         a pointer to the DosList entry for that device is returned.
  112.  
  113.     SEE ALSO
  114.         DeviceFromHandler(), DevNameFromLock()
  115.  
  116. dopus5.library/DevNameFromLock                 dopus5.library/DevNameFromLock
  117.  
  118.     NAME
  119.         DevNameFromLock - return the full pathname of a file
  120.  
  121.     SYNOPSIS
  122.         DevNameFromLock(lock, buffer, size)
  123.                          D1     D2     D3
  124.  
  125.         BOOL DevNameFromLock(BPTR, char *, long);
  126.  
  127.     FUNCTION
  128.         Returns a fully qualified path for the lock. The only difference
  129.         between this function and the equivalent DOS library routine is
  130.         that the device name of the disk is returned, rather than the
  131.         volume name.
  132.  
  133.         For example, if the NameFromLock() routine returned :
  134.  
  135.             Workbench:S/startup-sequence
  136.  
  137.         The DevNameFromLock() routine would return :
  138.  
  139.             DH0:S/startup-sequence
  140.  
  141.     INPUTS
  142.         lock - filelock to obtain the path for
  143.         buffer - buffer to store path
  144.         size - size of buffer
  145.  
  146.     RESULT
  147.         This function returns TRUE if it succeeds.
  148.  
  149.     SEE ALSO
  150.         DeviceFromLock(), dos.library/NameFromLock()
  151.  
  152. dopus5.library/FreeDosPathList                 dopus5.library/FreeDosPathList
  153.  
  154.     NAME
  155.         FreeDosPathList - free a DOS path list
  156.  
  157.     SYNOPSIS
  158.         FreeDosPathList(list)
  159.                          A0
  160.  
  161.         void FreeDosPathList(BPTR);
  162.  
  163.     FUNCTION
  164.         This function frees a standard DOS path list, by unlocking each
  165.         lock and FreeVec()ing each entry.
  166.  
  167.     INPUTS
  168.         list - pointer to head of list
  169.  
  170.     RESULT
  171.         The list is freed.
  172.  
  173.     SEE ALSO
  174.         GetDosPathList()
  175.  
  176. dopus5.library/GetDosPathList                   dopus5.library/GetDosPathList
  177.  
  178.     NAME
  179.         GetDosPathList - get a copy of a DOS path list
  180.  
  181.     SYNOPSIS
  182.         GetDosPathList(list)
  183.                         A0
  184.  
  185.         BPTR GetDosPathList(BPTR);
  186.  
  187.     FUNCTION
  188.         This routine has two uses. The first is to copy an existing DOS
  189.         path list that you supply. The second is to attempt to find and copy
  190.         the system path list.
  191.  
  192.     INPUTS
  193.         list - path list to copy or NULL
  194.  
  195.     RESULT
  196.         If you supply a path list, it will be copied and the address of the
  197.         first entry of the new list will be returned.
  198.  
  199.         If you pass NULL, this routine attempts to find a system path list to
  200.         copy. The Amiga has no definitive path list, so the only way to
  201.         obtain one is to copy it from another process. This routine looks for
  202.         the following processes (in order) : Workbench, Initial CLI, Shell
  203.         Process, New_WShell and Background CLI. If one of these processes is
  204.         found and it has a valid path list, that list is copied and returned
  205.         to you.
  206.  
  207.     NOTES
  208.         If Workbench is not running, Opus creates a dummy task called
  209.         'Workbench', purely to provide a path list for programs that use this
  210.         method.
  211.  
  212.     SEE ALSO
  213.         FreeDosPathList()
  214.  
  215. dopus5.library/GetFileVersion                   dopus5.library/GetFileVersion
  216.  
  217.     NAME
  218.         GetFileVersion - get a file's version information
  219.  
  220.     SYNOPSIS
  221.         GetFileVersion(name, verptr, revptr, date, progress)
  222.                         A0     D0      D1     A1      A2
  223.  
  224.         BOOL GetFileVersion(char *, short *, short *,
  225.                             struct DateStamp *, APTR);
  226.  
  227.     FUNCTION
  228.         This routine examines the given file and returns the file's version
  229.         number and revision, and creation date if available. It looks primarily
  230.         for a $VER string, but also understands the format of libraries,
  231.         devices, etc, and can extract the version from the Romtag structure in
  232.         the file. You can also supply a Progress handle if you want to use a
  233.         progress indicator while looking for the version information.
  234.  
  235.     INPUTS
  236.         name - full pathname of file to examine
  237.         verptr - pointer to short to receive the version number
  238.         revptr - pointer to short to receive the revision number
  239.         date - pointer to DateStamp structure (NULL if no date needed)
  240.         progress - pointer to progress indicator (or NULL)
  241.  
  242.     RESULT
  243.         Returns TRUE if a valid version number was found (this does not
  244.         necessarily mean that a date was found too).
  245.  
  246. dopus5.library/IsDiskDevice                       dopus5.library/IsDiskDevice
  247.  
  248.     NAME
  249.         IsDiskDevice - determine if a device is a DOS storage device
  250.  
  251.     SYNOPSIS
  252.         IsDiskDevice(handler)
  253.                        A0
  254.  
  255.         BOOL IsDiskDevice(struct MsgPort *);
  256.  
  257.     FUNCTION
  258.         This function takes a pointer to a handler (message port) and
  259.         returns TRUE if the device is for storage (eg a disk or a hard
  260.         drive), and FALSE if it is not.
  261.  
  262.     INPUTS
  263.         handler - pointer to handler message port
  264.  
  265. dopus5.library/LaunchCLI                             dopus5.library/LaunchCLI
  266.  
  267.     NAME
  268.         LaunchCLI - launch a program as a CLI process
  269.  
  270.     SYNOPSIS
  271.         LaunchCLI(name, screen, curdir, input, output, flags, stack)
  272.                    A0     A1      D0      D1     D2     D3     D4
  273.  
  274.         BOOL LaunchCLI(char *, struct Screen *, BPTR, BPTR, BPTR, short, long);
  275.  
  276.     FUNCTION
  277.         This routine makes it easy to launch a program as a CLI process. The
  278.         launched process will have a full path list and copy of local
  279.         environment variables. You can have the process launched synchronously,
  280.         which means this function would not return until the process quit.
  281.         The stack size defaults to 4096 bytes, but you may specify your own
  282.         stack size by setting the LAUNCHF_USE_STACK flag.
  283.  
  284.     INPUTS
  285.         name - name of the program to launch, including any arguments
  286.         screen - a screen for errors to appear on (or NULL for default)
  287.         curdir - lock for current directory, or NULL for default
  288.         input - file handle for standard input, or NULL
  289.         output - file handle for standard output, or NULL
  290.         flags - set LAUNCHF_WAIT flag if you want to wait for the process to return
  291.                 set LAUNCHF_USE_STACK flag if you are specifying a stack size
  292.         stack - stack size to use if LAUNCHF_USE_STACK flag is set
  293.  
  294.     RESULT
  295.         Returns TRUE if the process was launched successfully. If the
  296.         'wait' parameter was set to TRUE, will not return until the child
  297.         process does.
  298.  
  299.     NOTES
  300.         This function will search the current path list for your program
  301.         if you do not specify the full path.
  302.  
  303.     SEE ALSO
  304.         LaunchWB, dos.library/SystemTagList
  305.  
  306. dopus5.library/LaunchWB                               dopus5.library/LaunchWB
  307.  
  308.     NAME
  309.         LaunchWB - launch a program as a Workbench process
  310.  
  311.     SYNOPSIS
  312.         LaunchWB(name, screen, wait)
  313.                    A0     A1    D0
  314.  
  315.         BOOL LaunchWB(char *, struct Screen *, short);
  316.  
  317.     FUNCTION
  318.         This routine makes it easy to launch a program as a Workbench process.
  319.         Workbench processes expect to receive a startup message from the
  320.         launching process, and ordinarily the launching process must wait
  321.         until this message is replied to. Using this function relieves you
  322.         of this - you can launch the process and then forget about it.
  323.         The launched process will have a full path list and copy of local
  324.         environment variables.
  325.  
  326.     INPUTS
  327.         name - name of the program to launch, including any arguments
  328.         screen - a screen for errors to appear on (or NULL for default)
  329.         wait - wait for the process to return or not
  330.  
  331.     RESULT
  332.         Returns TRUE if the process was launched successfully. If the
  333.         'wait' parameter was set to 1, will not return until the child
  334.         process does. If the 'wait' parameter was set to 2, it will wait
  335.         for about 5 seconds for the process to return, before displaying
  336.         a requester giving the user the chance to wait some more. If 'wait'
  337.         is set to 0, it will return immediately and you do not need to
  338.         wait for a reply to the startup message.
  339.  
  340.     NOTES
  341.         This function will search the current path list for your program
  342.         if you do not specify the full path.
  343.  
  344.     SEE ALSO
  345.         LaunchCLI, LaunchWBNew, LaunchWBNotify, dos.library/SystemTagList
  346.  
  347. dopus5.library/LaunchWBNew                         dopus5.library/LaunchWBNew
  348.  
  349.     NAME
  350.         LaunchWBNew - launch a program as a Workbench process
  351.  
  352.     SYNOPSIS
  353.         LaunchWBNew(name, screen, wait, stack, default_tool)
  354.                    A0     A1    D0     D1        A2
  355.  
  356.         BOOL LaunchWBNew(char *, struct Screen *, short, long, char *);
  357.  
  358.     FUNCTION
  359.         This routine offers more control than LaunchWB() when launching a
  360.         Workbench process. It allows you to specify the stack size and
  361.         default tool that are used if the program you are launching is
  362.         a project and has no icon of its own.
  363.  
  364.     INPUTS
  365.         name - name of the program to launch, including any arguments
  366.         screen - a screen for errors to appear on (or NULL for default)
  367.         wait - wait for the process to return or not
  368.         stack - stack size to use if no icon present
  369.         default_tool - default tool to use if no icon or not set
  370.  
  371.     RESULT
  372.         Returns TRUE if the process was launched successfully. If the
  373.         'wait' parameter was set to 1, will not return until the child
  374.         process does. If the 'wait' parameter was set to 2, it will wait
  375.         for about 5 seconds for the process to return, before displaying
  376.         a requester giving the user the chance to wait some more. If 'wait'
  377.         is set to 0, it will return immediately and you do not need to
  378.         wait for a reply to the startup message.
  379.  
  380.     NOTES
  381.         This function will search the current path list for your program
  382.         if you do not specify the full path.
  383.  
  384.     SEE ALSO
  385.         LaunchWB, LaunchWBNotify, LaunchCLI, dos.library/SystemTagList
  386.  
  387. dopus5.library/LaunchWBNotify                   dopus5.library/LaunchWBNotify
  388.  
  389.     NAME
  390.         LaunchWBNotify - launch a program as a Workbench process
  391.  
  392.     SYNOPSIS
  393.         LaunchWBNotify
  394.              (name, screen, wait, stack, default_tool,
  395.                A0     A1    D0     D1        A2
  396.               proc_ptr, notify_ipc, flags)
  397.                A3         A4         D2
  398.  
  399.         BOOL LaunchWBNotify
  400.               (char *, struct Screen *, short, long, char *, 
  401.                struct Process **, IPCData *, ULONG);
  402.  
  403.     FUNCTION
  404.         This routine offers even more control than LaunchWBNew() when
  405.         launching a Workbench process. It allows you to specify the
  406.         stack size and default tool that are used if the program you are
  407.         launching is a project and has no icon of its own. It also lets
  408.         you obtain a pointer to the Process structure of the newly-
  409.         launched program, and specify an IPC port that will be notified
  410.         when the program exits.
  411.  
  412.     INPUTS
  413.         name - name of the program to launch, including any arguments
  414.         screen - a screen for errors to appear on (or NULL for default)
  415.         wait - wait for the process to return or not
  416.         stack - stack size to use if no icon present
  417.         default_tool - default tool to use if no icon or not set
  418.         proc_ptr - address of variable that receives the Process pointer
  419.         notify_ipc - IPC port recieves a message when the process exists
  420.         flags - unused, set to 0
  421.  
  422.     RESULT
  423.         Returns TRUE if the process was launched successfully. If the
  424.         'wait' parameter was set to 1, will not return until the child
  425.         process does. If the 'wait' parameter was set to 2, it will wait
  426.         for about 5 seconds for the process to return, before displaying
  427.         a requester giving the user the chance to wait some more. If 'wait'
  428.         is set to 0, it will return immediately and you do not need to
  429.         wait for a reply to the startup message.
  430.  
  431.         If 'proc_ptr' is specified, the address of the new Process structure
  432.         will be returned in it. If an IPC port is specified for 'notify_ipc',
  433.         it will receive an IPC_GOT_GOODBYE message when the process exits.
  434.         The 'data' field of the IPCMessage will contain the old Process
  435.         pointer so you can determine which process it was that exited.
  436.         Note that you must set the 'wait' parameter to 1 if you want a
  437.         notification message sent.
  438.  
  439.     NOTES
  440.         This function will search the current path list for your program
  441.         if you do not specify the full path.
  442.  
  443.     SEE ALSO
  444.         LaunchWB, LaunchWBNew, LaunchCLI, dos.library/SystemTagList
  445.  
  446. dopus5.library/ParseDateStrings               dopus5.library/ParseDateStrings
  447.  
  448.     NAME
  449.         ParseDateStrings - parse a date/time string into separate buffers
  450.  
  451.     SYNOPSIS
  452.         ParseDateStrings(string, date, time, rangeptr)
  453.                            A0     A1    A2      A3
  454.  
  455.         char *ParseDateStrings(char *, char *, char *, long *);
  456.  
  457.     FUNCTION
  458.         This function takes a date/time string (eg "8-12-95 10:34:18") and
  459.         splits the date and time elements into separate buffers. It also
  460.         supports the use of the '>' character to indicate ranges. For
  461.         example, "10-jan-94 > 15-jun-95" would indicate any date between
  462.         those dates.
  463.  
  464.     INPUTS
  465.         string - combined date/time string. This routine is smart enough
  466.                  to handle it if the time comes before the date, or
  467.                  vice versa, and it also deals reasonably well with
  468.                  different types of date inputs.
  469.         date - buffer to receive the date component (>=22 bytes)
  470.         time - buffer to receive the time component (>=22 bytes)
  471.         rangeptr - long pointer to receive the range code (or NULL)
  472.  
  473.     RESULT
  474.         The return from this function is a pointer to the end of the
  475.         parsed part of the input string. If the range returns RANGE_BETWEEN
  476.         (to signify a range between two dates), you will need to call
  477.         ParseDateStrings() again on the remainder of the string to get the
  478.         next date and time.
  479.  
  480.     SEE ALSO
  481.         DateFromStrings()
  482.  
  483. dopus5.library/SearchFile                           dopus5.library/SearchFile
  484.  
  485.     NAME
  486.         SearchFile - search a file or buffer for a text string
  487.  
  488.     SYNOPSIS
  489.         SearchFile(file, text, flags, buffer, bufsize)
  490.                     A0    A1     D0     A2      D1
  491.  
  492.         long SearchFile(APTR, UBYTE *, ULONG, UBYTE *, ULONG);
  493.  
  494.     FUNCTION
  495.         This routine searches a file, either on disk or in memory, for
  496.         a specified text string. It supports hex or decimal ascii values,
  497.         and limited wildcard searching. To search for a hex string,
  498.         the supplied search string should begin with a $ and then consist
  499.         of two-character hex codes. When searching for plain text, a
  500.         decimal ascii value can be specified with a \ character (eg \127).
  501.         A literal \ is given as \\. A question mark (?) is used as a
  502.         single wildcard character in both hex and text searches.
  503.  
  504.     INPUTS
  505.         file - buffered IO file handle
  506.         text - text string to search for
  507.         flags - Combination of the following flags :
  508.  
  509.                    SEARCH_NOCASE     - not case sensitive
  510.                    SEARCH_WILDCARD   - support ? as a wildcard character
  511.                    SEARCH_ONLYWORDS  - only match whole words
  512.  
  513.         buffer - memory buffer to search if no file specified
  514.         bufsize - size of memory buffer, or amount of disk file to search
  515.  
  516.     RESULT
  517.         If the supplied string is found, the offset within the file/buffer
  518.         of the first instance is returned. If no match is found or an error
  519.         occurs, -1 is returned.
  520.  
  521. dopus5.library/SetEnv                                   dopus5.library/SetEnv
  522.  
  523.     NAME
  524.         SetEnv - set a global environment variable
  525.  
  526.     SYNOPSIS
  527.         SetEnv(name, string, permanent)
  528.                 A0     A1        D0
  529.  
  530.         void SetEnv(char *, char *, BOOL);
  531.  
  532.     FUNCTION
  533.         This routine sets the named environment variable to the supplied
  534.         string value, and optionally saves it permanently.
  535.  
  536.     INPUTS
  537.         name - name of the variable to set
  538.         string - text string to set the variable to (must be null-terminated)
  539.         permanent - set to TRUE if you want the variable saved
  540.  
  541.     RESULT
  542.         The environment variable will be created if it does not exist. Any
  543.         sub-directories that are needed will also be created. For example,
  544.         if you set the variable "foo/bar/baz", the directories "env:foo"
  545.         and "env:foo/bar" would be automatically created if they did not
  546.         exist. If you set the 'permanent' flag to TRUE, the variable
  547.         will also be created in the ENVARC: directory.
  548.  
  549.     SEE ALSO
  550.         dos.library/GetVar
  551.  
  552.